ROS 2 Humble安装指南

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

本文档说明在 Quectel Pi M1 开发板（Debian 13 trixie / ARM64）上从源码构建 ROS 2 Humble 的方法。ROS 2 Humble 官方发行版面向 Ubuntu 22.04，Debian 13 下无现成 apt 包，需在板端从源码构建。本文档所有步骤均在 M1（内核 5.15.180-gki-consolidate，Python 3.13.5）上实测通过。

简介

ROS 2（Robot Operating System 2）是面向机器人开发的分布式通信框架，Humble 为其长期支持（LTS）版本。在 M1 开发板上从源码构建 ROS 2 Humble 的特点：

  • 可裁剪：只构建需要的功能包，可跳过 Fast DDS、Connext 等商业中间件（本文档使用 Cyclone DDS）；

  • 板端验证：直接基于 M1 的 Debian 13 系统构建，产物与硬件环境匹配；

  • 可复现：工作空间结构与构建参数可模板化，便于 CI 与多设备同步。

磁盘空间提示： M1 根分区（/）仅 7.8 GB，完整编译需 10 GB 以上空间。本文档将工作空间部署在 /data 分区（约 40 GB，SD 卡 mmcblk0p82），编译全程实测无空间压力。

准备工作

系统要求

项目

要求

操作系统

Debian GNU/Linux 13 (trixie)

架构

ARM64（aarch64）

磁盘

建议部署在 /data 分区（根分区空间不足）；源码约 1 GB，编译产物约 3 GB

内存

≥ 3 GB（M1 为 3.5 GB，编译较慢但可用）

网络

可访问 GitHub（克隆源码）与 Debian 软件源（安装依赖）

编译时间

约 3–5 小时（M1 实测，含排障）

网络环境（内网/无外网场景）

若板子无法直连外网，可通过 宿主机代理 + adb reverse 提供网络：

# 宿主机：启动 HTTP 代理（如 python 简易代理，监听 3128）
# 板子：通过 adb reverse 将板内 3128 端口转发到宿主机
adb reverse tcp:3128 tcp:3128

# 板子上设置代理环境变量
export http_proxy=http://127.0.0.1:3128 https_proxy=http://127.0.0.1:3128
export HTTP_PROXY=http://127.0.0.1:3128 HTTPS_PROXY=http://127.0.0.1:3128

# 配置 apt 使用代理
echo 'Acquire::http::Proxy "http://127.0.0.1:3128";' > /etc/apt/apt.conf.d/01proxy
echo 'Acquire::https::Proxy "http://127.0.0.1:3128";' >> /etc/apt/apt.conf.d/01proxy

注意： 板子默认时间可能错误（1970 年），会导致 HTTPS 证书校验失败，需先同步时间：date -s "$(date '+%Y-%m-%d %H:%M:%S')"（或配置 NTP）。

安装步骤

安装基础依赖包

sudo apt-get update
sudo apt-get install -y \
    python3-flake8-blind-except python3-flake8-class-newline python3-flake8-deprecated \
    python3-mypy python3-pip python3-pytest python3-pytest-cov python3-pytest-mock \
    python3-pytest-repeat python3-pytest-rerunfailures python3-pytest-runner \
    python3-pytest-timeout python3-rosdep2 python3-colcon-core \
    vcstool build-essential git \
    python3-numpy python3-numpy-dev \
    libacl1-dev uncrustify

创建工作空间（部署到 /data）

# 根分区空间不足时，使用 /data 分区并建软链
sudo mkdir -p /data/ros2_humble/src
sudo ln -s /data/ros2_humble /root/ros2_humble
cd /data/ros2_humble

获取 ROS 2 Humble 源代码

cd /data/ros2_humble
mkdir -p src
wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
vcs import src < ros2.repos

ros2.repos 包含约 100 个仓库（实测 105 个），源码约 600 MB。若 vcs 卡在某仓库（如 Fast-DDS 大仓库），可改用浅克隆脚本逐个拉取。

安装系统依赖项

sudo rosdep init
rosdep update
cd /data/ros2_humble
rosdep install --from-paths src --ignore-src --rosdistro humble -y -r \
  --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-vcstool \
              ignition-math6 ignition-cmake2 ignition-common3 ignition-transport8"

跳过的包说明： fastcdr、rti-connext-dds（商业/可选）；urdfdom_headers、python3-vcstool（已装）；ignition-*（Debian 13 不可用，Gazebo 相关）。

常见错误（可忽略）： python3-sip-dev 失败（GUI 工具 rqt 依赖）、python3-nose 失败（Python 3.12+ 废弃），均不影响核心功能。

编译源码

编译策略： 使用 Cyclone DDS（跳过 Fast DDS/Connext 编译，显著减少耗时与空间），只构建到 demo_nodes 的最小依赖链：

cd /data/ros2_humble
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

colcon build --symlink-install \
  --packages-up-to demo_nodes_cpp demo_nodes_py \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
  --packages-skip \
  rmw_connextdds rmw_connextdds_common rmw_connextddsmicro rti_connext_dds_cmake_module \
  rviz_assimp_vendor tinyxml_vendor libcurl_vendor zstd_vendor sqlite3_vendor \
  yaml_cpp_vendor shared_queues_vendor

实测编译约 130 个包、耗时 40+ 分钟（含大包 fastrtps 26 分钟、iceoryx_posh 等）。编译完成后可追加构建 ros2cli 命令行工具：

source /data/ros2_humble/install/setup.bash
colcon build --packages-select ros2cli ros2node ros2topic ros2msg ros2service ros2action ros2param \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

编译问题与解决方法（M1 实测）

问题 1：rmw 编译报 unknown type name ‘bool’

新版 GCC 更严格，rmw/time.h 缺 #include <stdbool.h>。修复：

sed -i 's|#include <stdint.h>|#include <stdbool.h>\n#include <stdint.h>|' \
  /data/ros2_humble/src/ros2/rmw/rmw/include/rmw/time.h

问题 2：vendor 包（zstd/sqlite3/yaml_cpp 等）下载超时被 abort

这些包编译时从外网下载第三方源码，代理不稳会失败。解决：预先用代理下载归档到 CMake 缓存路径（build//*-prefix/src/），文件存在且 MD5 匹配时 CMake 会跳过下载；超大文件（如 assimp 45 MB）可在宿主机下载后 adb push 到板子。

问题 3：rmw_implementation 报 Failed to find …/package.sh

构建系统查找被跳过包的 package.sh 环境钩子。用占位脚本绕过：

for p in rti_connext_dds_cmake_module rmw_connextdds_common rmw_connextdds rmw_connextddsmicro; do
  mkdir -p /data/ros2_humble/install/$p/share/$p
  printf '#!/bin/sh\n# placeholder for %s\n' "$p" > /data/ros2_humble/install/$p/share/$p/package.sh
  chmod +x /data/ros2_humble/install/$p/share/$p/package.sh
done

问题 4：rclpy 编译报 Imported target “pybind11::headers” includes non-existent path “/include”

Debian 打包 pybind11 的 CMake 前缀路径 bug。修复 pybind11Targets.cmake 硬编码 include 路径：

sed -i 's|INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include"|INTERFACE_INCLUDE_DIRECTORIES "/usr/include"|' \
  /usr/lib/cmake/pybind11/pybind11Targets.cmake

问题 5：消息包编译报 ModuleNotFoundError

缺 lark（rosidl_parser 依赖）与 numpy C 头文件：

pip3 install lark netifaces
apt-get install -y python3-numpy-dev   # 提供 numpy/ndarrayobject.h

问题 6：rosidl_cli 反复报 File exists (package.dsv)

symlink-install 模式对 Python 包资源文件的已知冲突。先单独用 copy 模式构建：

rm -rf build/rosidl_cli install/rosidl_cli
colcon build --packages-select rosidl_cli \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

问题 7：iceoryx_posh 编译超时被 abort

该包编译需 5–10 分钟，并行构建时会被 colcon 判定超时。先单独构建：

colcon build --packages-select iceoryx_posh \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

问题 8：rosidl_default_generators 依赖 rosidl_generator_rs（Rust）

demo_nodes 不需要 Rust 生成器。从 package.xml 移除该依赖行：

sed -i '/rosidl_generator_rs/d' \
  /data/ros2_humble/src/ros2/rosidl_defaults/rosidl_default_generators/package.xml

环境变量设置

编译完成后，将 ROS 2 环境写入 ~/.bashrc 实现自动加载：

echo 'source /data/ros2_humble/install/setup.bash' >> ~/.bashrc
echo 'export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp' >> ~/.bashrc
source ~/.bashrc

使用测试

打开一个终端，运行 C++ talker：

ros2 run demo_nodes_cpp talker

打开另一个终端，运行 Python listener：

ros2 run demo_nodes_py listener

验证

M1 实测输出：

[INFO] [talker]: Publishing: 'Hello World: 3'
[INFO] [listener]: I heard: [Hello World: 13]

也可用 ros2 命令行验证话题：

ros2 topic list          # 应显示 /chatter /parameter_events /rosout
ros2 topic info /chatter # Type: std_msgs/msg/String, Publisher count: 1

C++ 与 Python API 互通正常，ROS 2 Humble 环境可用于后续应用开发。

常见问题

ros2 命令只显示 daemon/extension_points

说明 ros2cli 扩展命令（node/topic 等）未安装。按 3.5 节补充构建 ros2cli 系列包。

ros2 topic 报 No module named ‘netifaces’

pip3 install netifaces

talker 启动报缺 liblibstatistics_collector.so

未 source 环境导致 LD_LIBRARY_PATH 缺失。先 source /data/ros2_humble/install/setup.bash 再运行。

编译时内存不足（OOM）

M1 内存 3.5 GB，并行编译可能 OOM。可减少并行度：colcon build --parallel-workers 2 ...，或按 3.5 节先单独构建大包。

板子时间错误导致 HTTPS 失败

sudo date -s "$(date '+%Y-%m-%d %H:%M:%S')"

完整 ros2 功能包（rviz2 等）

本文档为最小化安装（demo_nodes 依赖链）。如需 GUI/仿真功能，可继续用 colcon build --packages-up-to rviz2 ... 增量构建（注意磁盘空间）。